namespace NICWebApi.Extensions.Caching.Interfaces;

/// <summary>
/// 缓存服务接口
/// 提供统一的缓存操作，支持内存缓存和分布式缓存
/// </summary>
public interface ISimpleCacheService
{
    /// <summary>
    /// 获取缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <returns>缓存项，不存在则返回默认值</returns>
    T Get<T>(string key);

    /// <summary>
    /// 异步获取缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <param name="token">取消令牌</param>
    /// <returns>缓存项，不存在则返回默认值</returns>
    Task<T> GetAsync<T>(string key, CancellationToken token = default);

    /// <summary>
    /// 设置缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <param name="value">缓存值</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <returns>是否设置成功</returns>
    bool Set<T>(string key, T value, int? expiration = null);

    /// <summary>
    /// 异步设置缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <param name="value">缓存值</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <param name="token">取消令牌</param>
    /// <returns>是否设置成功</returns>
    Task<bool> SetAsync<T>(string key, T value, int? expiration = null, CancellationToken token = default);

    /// <summary>
    /// 移除缓存项
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <returns>是否移除成功</returns>
    bool Remove(string key);

    /// <summary>
    /// 异步移除缓存项
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <param name="token">取消令牌</param>
    /// <returns>是否移除成功</returns>
    Task<bool> RemoveAsync(string key, CancellationToken token = default);

    /// <summary>
    /// 通过模式移除多个缓存项
    /// </summary>
    /// <param name="pattern">模式</param>
    /// <returns>移除的键数量</returns>
    int RemoveByPattern(string pattern);

    /// <summary>
    /// 异步通过模式移除多个缓存项
    /// </summary>
    /// <param name="pattern">模式</param>
    /// <param name="token">取消令牌</param>
    /// <returns>移除的键数量</returns>
    Task<int> RemoveByPatternAsync(string pattern, CancellationToken token = default);

    /// <summary>
    /// 判断缓存键是否存在
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <returns>是否存在</returns>
    bool Exists(string key);

    /// <summary>
    /// 异步判断缓存键是否存在
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <param name="token">取消令牌</param>
    /// <returns>是否存在</returns>
    Task<bool> ExistsAsync(string key, CancellationToken token = default);

    /// <summary>
    /// 获取或添加缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <param name="valueFactory">缓存值工厂</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <returns>缓存值</returns>
    T GetOrSet<T>(string key, Func<T> valueFactory, int? expiration = null);

    /// <summary>
    /// 异步获取或添加缓存项
    /// </summary>
    /// <typeparam name="T">缓存项类型</typeparam>
    /// <param name="key">缓存键</param>
    /// <param name="valueFactory">缓存值工厂</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <param name="token">取消令牌</param>
    /// <returns>缓存值</returns>
    Task<T> GetOrSetAsync<T>(string key, Func<Task<T>> valueFactory, int? expiration = null, CancellationToken token = default);

    /// <summary>
    /// 获取所有匹配模式的缓存键
    /// </summary>
    /// <param name="pattern">模式</param>
    /// <returns>匹配的缓存键列表</returns>
    IEnumerable<string> GetKeysByPattern(string pattern);

    /// <summary>
    /// 异步获取所有匹配模式的缓存键
    /// </summary>
    /// <param name="pattern">模式</param>
    /// <param name="token">取消令牌</param>
    /// <returns>匹配的缓存键列表</returns>
    Task<IEnumerable<string>> GetKeysByPatternAsync(string pattern, CancellationToken token = default);

    /// <summary>
    /// 清空所有缓存
    /// </summary>
    void Clear();

    /// <summary>
    /// 异步清空所有缓存
    /// </summary>
    /// <param name="token">取消令牌</param>
    /// <returns>任务</returns>
    Task ClearAsync(CancellationToken token = default);

    /// <summary>
    /// 获取缓存项过期时间
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <returns>缓存项过期时间，不存在则返回null</returns>
    TimeSpan? GetExpiration(string key);

    /// <summary>
    /// 异步获取缓存项过期时间
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <param name="token">取消令牌</param>
    /// <returns>缓存项过期时间，不存在则返回null</returns>
    Task<TimeSpan?> GetExpirationAsync(string key, CancellationToken token = default);

    /// <summary>
    /// 重新设置缓存项过期时间
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <returns>是否设置成功</returns>
    bool Refresh(string key, int? expiration = null);

    /// <summary>
    /// 异步重新设置缓存项过期时间
    /// </summary>
    /// <param name="key">缓存键</param>
    /// <param name="expiration">过期时间（秒）</param>
    /// <param name="token">取消令牌</param>
    /// <returns>是否设置成功</returns>
    Task<bool> RefreshAsync(string key, int? expiration = null, CancellationToken token = default);
}